Description

Implements the v1 contextManager facade as designed in strands-agents/docs#831.

Adds a contextManager parameter to AgentConfig that pre-composes the SDK's context management primitives into a single configuration surface. An internal ContextManager plugin composes sub-plugins (ContextCompression, ContextOffloader) that handle the actual behavior.

Architecture

ContextManager (internal plugin)
├── ContextCompression (sub-plugin)
│   ├── Proactive compression (BeforeModelCallEvent)
│   ├── Reactive overflow recovery (AfterModelCallEvent)
│   └── Sliding window enforcement (AfterInvocationEvent)
└── ContextOffloader (sub-plugin)
    ├── Tool result caching (AfterToolCallEvent)
    └── retrieve_offloaded_content tool

Sub-plugins work independently when used standalone. User-provided plugins with matching names take precedence over managed sub-plugins. When contextManager is set, ContextCompression takes priority — NullConversationManager is used (same pattern as other dedicated-param plugins like retryStrategy, sessionManager).

What ships

• contextManager parameter on AgentConfig — accepts "auto" or a config object
• ContextCompression plugin — proactive/reactive compression with own reduction logic (truncate or summarize)
• ContextOffloader — stays in vended-plugins/context-offloader/, composed internally by ContextManager
• Message pinning (context-manager/compression/protection.ts) — pinMessageTool for agent-controlled pinning at runtime. Internal utilities (pinMessage, unpinMessage, isPinned, isProtected) not exported; programmatic pinning API deferred.
• protectFirst — number of messages at the start of the conversation to protect from eviction
• estimateInputTokens() utility — shared token estimation in src/context-manager/token-estimation.ts
• <summary> XML tags — summarized messages are wrapped in <summary> tags so the model can distinguish framework-injected summaries from user content
• conversationManager marked as pending deprecation — still works, JSDoc-tagged

Public API Surface

New on AgentConfig:

• contextManager?: ContextManagerParam

New exports:

• pinMessageTool (agent-invokable tool)
• ContextManagerParam (type)

All classes (ContextManager, ContextCompression, ContextOffloader) are internal. ContextOffloader remains accessible via the vended-plugins/context-offloader sub-path for backward compat.

Configuration model

Two semantics depending on whether strategy: 'auto' is present:

Override (strategy: 'auto') — starts with everything enabled, you override specific settings:

contextManager: "auto"                                              // everything with defaults
contextManager: { strategy: 'auto', compression: { windowSize: 60 } }  // auto, tweak compression
contextManager: { strategy: 'auto', offloader: { threshold: 5000 } }   // auto, tweak offloader

Additive (no strategy) — starts with nothing, you enable what you want:

contextManager: { compression: true }                               // only compression
contextManager: { compression: 'summarize' }                        // only summarize compression
contextManager: { offloader: true }                                 // only offloading
contextManager: { compression: true, offloader: true }              // both (same as "auto")
contextManager: {}                                                  // nothing enabled

Compression config (discriminated union on method)

compression: true                                       // defaults
compression: 'truncate'                                 // method shorthand
compression: 'summarize'                                // method shorthand
compression: { method: 'truncate', windowSize: 30 }     // full config
compression: { method: 'summarize', summaryRatio: 0.5 } // full config
compression: { protectFirst: 2 }                        // protect first 2 messages

Defaults (when enabled via "auto")

Plugin registration

contextManager must be passed via the dedicated parameter — same pattern as conversationManager, retryStrategy, and sessionManager. No guards for misuse in plugins[] (consistent with other special-cased plugins).

Deprecation Plan

The following are marked as pending deprecation in v1 and will be removed in v2:

• AgentConfig.conversationManager → contextManager: { compression: ... }
• Agent._estimateInputTokens() → shared estimateInputTokens() utility
• BeforeModelCallEvent.projectedInputTokens → future contextManager budget API
• ConversationManager, SlidingWindowConversationManager, SummarizingConversationManager, NullConversationManager → ContextCompression plugin
• vended-plugins/context-offloader/ sub-path → import from @strands-agents/sdk directly

Breaking Changes

None. All changes are additive. Existing behavior is unchanged when contextManager is not set.

Related Issues

Documentation PR

strands-agents/docs#831

Type of Change

New feature

Testing

• Type check passes
• Lint passes
• All 2915 tests pass (106 test files)
• 60 new unit tests covering: token estimation, compression plugin, truncate/summarize strategies, protection logic, context manager resolution

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.